COMMENT ⊗   VALID 00004 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002		     Programming for the Ethernet device on WAITS
C00005 00003				     Raw packet mode
C00008 00004				       BSP mode
C00014 ENDMK
C⊗;
	     Programming for the Ethernet device on WAITS

     The Ethernet on WAITS is implemented as a device driver for
device PUP:.  Most of the standard WAITS I/O UUOs apply to the PUP:
device.  The Ethernet may be used either in "BSP mode" (in which case
the system provides flow control) or in "raw packet mode".  This is
determined by the I/O data mode the PUP: channel is OPENed or INITed
in.  Dump mode indicates raw packet mode, which a buffered I/O mode
indicates BSP mode.  It is possible while an I/O channel is open to
switch modes via the SETSTS UUO, although I don't recommend it and
anybody who does it will probably be boiled in oil and forced to
program in PASCAL or FORTRAN or some such other horrendous language.

     The I/O UUO's described here may return any of the following
error bits in the I/O status word if they fail.

Name	Interpretation
----	--------------
IOIMPM	Connection not in proper state; the connection either never
	 was opened or is in the process of closing.
IODERR	The console PDP-11 did not accept the Pup (it is probably
	 sick and needs attention).  Only happens on a datagram OUTPUT.
IODTER	Time out; the Pup was not answered within a pre-determined
	 time out interval.  Probably the other host is dead or at
	 least the remote server is down.
IOBKTL	The other host sent us a Pup larger than we can handle in BSP
	 mode.  Since we never allocate it a Pup that large, it is
	 violating protocol.
IODEND	The connection has closed; no more Pups are available for input.
			     Raw packet mode

     Before sending any Pups in raw packet mode, a link must be
established.  A link is a system resource which specifies the local
socket, the remote socket, and the remote host.  A link is created
by using the LOOKUP UUO as follows:
	LOOKUP <channel>,<block>
	 <failed, local socket busy or no more links available>
	<success>
	...
block:	<local socket>
	<foreign socket>
	<foreign host>
The LOOKUP UUO is an illegal UUO if the I/O channel is not in dump
mode or if the arguments are invalid in any way.  A LOOKUP given
on an I/O channel which already has a link changes that link's
parameters.

     A link is destroyed by the UTPCLR UUO:
	UPTCLR <channel>,
Link destruction is also done by a RELEASE UUO, except that UTPCLR
does not release the I/O channel.

     A Pup is read with the INPUT UUO, as follows:
	INPUT <channel>,<block>
	...
block:	<Pup readin block, at least 140. words long>
The Pup readin block receives the entire Pup including the Ethernet
header.  The system already has validated the checksum.  If no Pups
are available to read INPUT will wait until one appears.

     A Pup is sent with the OUTPUT UUO, as follows:
	OUTPUT <channel>,<block>
	...
block:	<Pup output block, at most 140. words long>
The Pup output block is an image of the Pup to be sent.  The system
will fill in most of the Pup header, including the Ethernet message
type, the host/sockets, and the checksum; however the user may
specify the Pup type.  OUTPUT is an illegal UUO if the length of the
Pup is too large or too small.

     One Pup MTAPE is meaningful in raw Pup mode, the .MTSIP function.
See the next page for further details.
			       BSP mode

     BSP mode is a simple data stream mode, using the standard WAITS
I/O UUO's (IN/OUT/INPUT/OUTPUT).  From time to time on input, there
will be padding nulls at the end of a word.  These are indicated by
the low order two bits of the word being non-zero; these bits contain
the number of significant data bytes in the word (note that a zero
count means that the entire word is significant).  Many user programs
will ignore nulls and need not worry about checking this count.

     For buffers sent without filling up a packet's worth of data,
the output code checks the byte count in the user's buffer header.
Therefore the buffer header byte count must accurately reflect the
number of free bytes in the buffer.  For most programs this is no
hardship unless the programmer tries to be cute.

     A CLOSE UUO (either executed directly or implicitly by a RELEASE)
closes the BSP connection.

     Non-I/O portions of the connection are accomplished by the MTAPE
UUO.  An MTAPE call is of the form
	MTAPE <channel>,<block>
	 <error return>
	<success return>
	...
block:	<function code>
	<status word>
	<possible function arguments>


     The words of a PUP MTAPE block is:
Name	Offset	Interpretation
-----	-----	--------------
MT%FCN	0	Function code.
MT%STA	1	Status word, set by all functions.
MT%MRK	2	Mark value (read by .MTSMR, set by .MTRMR).
MT%SKT	2	Socket number (read by .MTCON and .MTLSN), note that
		 this is the same offset as MT%MRK, but no function
		 uses both.
MT%HST	3	Host address (read by .MTCON, set by .MTLSN).

     The function code is one of the following:
Name	Value	Interpretation
-----	-----	--------------
.MTCON	0	Connect; this function establishes a connection to
		 the remote host with arguments in MT%SKT and MT%HST.
.MTLSN	1	Listen; wait for a connection request from a host on
		 the socket in MT%SKT, establish a connection, return
		 the remote host address in MT%HST.
.MTSMR	2	Send Mark; send a AMark Pup to the remote host with
		 Mark type in MT%MRK.
.MTRMR	3	Read Mark; return the type of the last read Mark in
		 MT%MRK.
.MTSIP	4	Skip if Input Present; return success if there is at
		 least one Pup on the input list (ie, an INPUT UUO
		 will not wait for a packet).
.MTSIN	5	Send Interrupt; send an Interrupt Pup.

     The status word presently is zero on a successful MTAPE, or
contains the error code on a failing MTAPE.  The error codes are:

Name	Value	Interpretation
-----	-----	--------------
%MTNIM	1	Not implemented.
%MTCIU	2	Channel in use; the channel is already associated
		 with a link, so an .MTCON or .MTLSN MTAPE is illegal.
%MTNLA	3	No links available; the system's table of Ethernet
		 links is full, therefore a new link cannot be
		 created by an .MTCON or .MTLSN MTAPE.
%MTNIA	4	No input available; this is the non-skip status
		 returned by an .MTSIP MTAPE.
%MTISK	5	Invalid socket; the socket for an .MTCON or .MTLSN
		 MTAPE is less than 1 or greater than $PUPMS
		 (currently 1000), the system maximum Pup server
		 socket.
%MTSIU	6	Socket in use; an .MTLSN MTAPE was done when a link
		 already exists.
%MTNLK	7	No link; the function requires a link to be associated
		 with the I/O channel, but none has been set up.
%MTTMO	10	Time out; the request didn't get the appropriate reply
		 from the host within a "reasonable" time, or a .MTLSN
		 took longer than 30 seconds.